<!-- Copyright (C) 2019-2021 Junruoyu Zheng. Home page: https://junruoyu-zheng.gitee.io/ligral

     Distributed under MIT license.
     See file LICENSE for detail or copy at https://opensource.org/licenses/MIT
-->
<!DOCTYPE html>
<html lang="en">
 <head>
  <title>
   接口签名
  </title>
  <meta charset="utf-8"/>
  <meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport"/>
  <!-- Main CSS -->
  <link href="/ligral/css/style.css" rel="stylesheet"/>
  <link href="/ligral/css/rolling.css" rel="stylesheet"/>
  <link href="/ligral/css/custom.css" rel="stylesheet"/>
  <link href="/ligral/css/katex.min.css" rel="stylesheet"/>
  <link href="/ligral/avatar.png" rel="shortcut icon" type="image/x-icon"/>
  <!-- Font Awesome -->
  <script crossorigin="anonymous" src="https://kit.fontawesome.com/14294c79e2.js">
  </script>
 </head>
 <body>
  <!-- Header -->
  <div class="header-wrap d-none d-md-block">
   <div class="container">
    <div class="row">
     <!-- Left header box -->
     <header class="col-6 text-left">
      <h1 class="letter-wrap title">
       Ligral
      </h1>
     </header>
    </div>
   </div>
  </div>
  <!-- Main navigation -->
  <nav class="navbar navbar-expand-md navbar-dark bg-primary">
   <div class="container">
    <!-- Company name shown on mobile -->
    <a class="navbar-brand d-md-none d-lg-none d-xl-none" href="#">
     Ligral
    </a>
    <!-- Mobile menu toggle -->
    <button aria-controls="mainNavbar" aria-expanded="false" aria-label="Toggle navigation" class="navbar-toggler" data-target="#mainNavbar" data-toggle="collapse" type="button">
     <span class="navbar-toggler-icon">
     </span>
    </button>
    <!-- Main navigation items -->
    <div class="collapse navbar-collapse" id="mainNavbar">
     <ul class="navbar-nav mr-auto">
      <li class="nav-item">
       <a class="nav-link" href="/ligral/index.html">
        主页
        <span class="sr-only">
         (current)
        </span>
       </a>
      </li>
      <li class="nav-item dropdown active">
       <a aria-expanded="false" aria-haspopup="true" class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button">
        文档
       </a>
       <div class="dropdown-menu navbar-dark bg-primary">
        <a class="dropdown-item" href="/ligral/quick-start.html">
         快速开始
        </a>
        <a class="dropdown-item" href="/ligral/user-guide">
         用户文档
        </a>
        <a class="dropdown-item" href="/ligral/dev-guide">
         开发文档
        </a>
        <a class="dropdown-item" href="/ligral/interface/">
         接口定义
        </a>
       </div>
      </li>
      <!-- <li class="nav-item">
                                <a class="nav-link" href="#">Services</a>
                        </li> -->
      <li class="nav-item">
       <a class="nav-link" href="/ligral/product.html">
        产品
       </a>
      </li>
      <li class="nav-item">
       <a class="nav-link" href="/ligral/contact.html">
        联系我们
       </a>
      </li>
     </ul>
     <!-- <form class="form-inline header-search-form my-2 my-lg-0">
                        <input class="form-control mr-sm-2" type="text" size="10"  placeholder="Search" aria-label="Search">
                        <button class="btn btn-secondary my-2 my-sm-0" type="submit">Search</button>
                    </form> -->
    </div>
   </div>
  </nav>
  <!-- Jumbtron / Slider -->
  <!-- Main content area -->
  <main class="container">
   <div class="row" style="flex-direction: row-reverse;">
    <!-- Main content -->
    <div class="col-sm-8">
     <article>
      <h1>
       接口签名
      </h1>
      <p>
       在一个规模宏大的仿真工程中，实现各个子系统之间的解耦的一种重要手段就是接口签名。接口签名实现了一种先定义后实现、定义与实现分离的建模方式。签名定义了一个节点在与其他节点交互时的全部接口信息，隐藏了内部实现逻辑。
      </p>
      <h3>
       语法
      </h3>
      <p>
       定义一个接口签名的语法如下所示：
      </p>
      <pre><code>signature SignatureName(inputs; outputs);
</code></pre>
      <p>
       与路由的属性语法十分类似，所不同之处有三点：
      </p>
      <ul>
       <li>
        关键字为
        <code>
         signature
        </code>
        而非
        <code>
         route
        </code>
       </li>
       <li>
        不可以声明签名的签名
       </li>
       <li>
        不需要写明参数列表
       </li>
      </ul>
      <p>
       此外由于没有主体部分，接口签名声明语句直接以
       <code>
        ;
       </code>
       结尾。之所以不可以声明签名的签名，是因为签名已经完全规定了一个结点的所有接口，声明了该签名的节点没有变化的自由，如果一个签名声明了另一个签名，那么它们就是同一个签名，重复定义没有意义。签名并没有规定节点应该采用什么样的参数列表，因为参数不属于接口的范畴。因此，实例化必须在路由层面进行，不能实例化一个接口签名。
      </p>
      <h3>
       用法
      </h3>
      <p>
       在
       <a href="route">
        上一节
       </a>
       中，签名的用法已经介绍了，这里再总结一下。签名除了再定义语句外还能出现在两个地方，一处是路由的定义语句：
      </p>
      <pre><code>route Route:NodeSignature (...) ...
</code></pre>
      <p>
       这表示路由
       <code>
        Route
       </code>
       声明了一个签名
       <code>
        NodeSignature
       </code>
       。另一处是路由的参数列表：
      </p>
      <pre><code>route Route2 (param:NodeSignature, ...; ...) ...
</code></pre>
      <p>
       这表示路由
       <code>
        Route2
       </code>
       中的参数
       <code>
        param
       </code>
       是一个节点，且该节点声明了
       <code>
        NodeSignature
       </code>
       签名。因此，在实例化
       <code>
        Route2
       </code>
       的时候，您就可以写：
      </p>
      <pre><code>Route2{param:Route, ...};
</code></pre>
      <p>
       请注意，此处的
       <code>
        :
       </code>
       并不是表明
       <code>
        param
       </code>
       声明了
       <code>
        Route
       </code>
       ，首先，
       <code>
        Route
       </code>
       是一个节点实例而非签名，不能被声明；其次，此处的
       <code>
        :
       </code>
       作用和 JSON 中的冒号类似，或者您也可以参考 C# 中可省参数的用法，代表将
       <code>
        Route
       </code>
       赋值给标识符
       <code>
        param
       </code>
       。
      </p>
      <h3>
       示例
      </h3>
      <p>
       在
       <a href="route">
        早先的文档
       </a>
       中给出了一个控制器的例子
       <code>
        PIDController
       </code>
       ，在
       <a href="../quick-start">
        快速开始
       </a>
       中有一个弹簧阻尼质量块系统
       <code>
        MassSpringDamper
       </code>
       。假设需要构建一个闭环模型，只需要把这两个模块连接起来即可。
      </p>
      <pre><code>MassSpringDamper[sys]{m:0.1, k:10, d:0.3, x0:1, v0: 0};
PIDController[controller]{Kp:1, Ki:0.1, Kd:4);
sys:x -&gt; controller -&gt; sys;
</code></pre>
      <p>
       这样一个闭环的弹簧阻尼质量块模型，很可能是需要复用的，因此将其定义成一个路由会是很好的选择。
      </p>
      <pre><code>route ClosedLoopMSD(m, k, d, x0, v0, Kp, Ki=0, Kd=0, tau=0.01; F; x, v)
    MassSpringDamper[sys]{m:m, k:k, d:d, x0:x0, v0:v0};
    PIDController[controller]{Kp:Kp, Ki:Ki, Kd:Kd, tau:tau);
    (sys:x -&gt; controller) + F -&gt; sys -&gt; (x, v);
end
</code></pre>
      <p>
       但是这么写弊端有很多。首先，所有节点的参数如果支持修改的话，都要定义在路由的参数列表里，并且所有缺省参数都必须要列明，并且显示赋值，这样极大地降低了语法的简洁性，并且可能造成参数标识符冲突等问题。其次，子节点的逻辑是固定的，如果您想把弹簧阻尼质量块替换成一个非线性版本，或者把 PID 控制器替换成滑模控制器，就必须要重新编写一个路由。
      </p>
      <p>
       利用 ligral 的签名语法，可以消除以上问题，保持简洁的语法。定义两个签名：
      </p>
      <pre><code>signature MSDSignature(F; x, v);
signature CTRSignature(x; u);
</code></pre>
      <p>
       分别规定了弹簧阻尼质量块的接口和控制器的接口。然后在闭环模型的定义里：
      </p>
      <pre><code>route ClosedLoopMSD(sys:MSDSignature, controller:CTRSignature; F; x, v)
    (sys:x -&gt; controller) + F -&gt; sys -&gt; (x, v);
end
</code></pre>
      <p>
       最后在实例化
       <code>
        ClosedLoopMSD
       </code>
       之前定义好
       <code>
        sys
       </code>
       和
       <code>
        controller
       </code>
       实例，并传入：
      </p>
      <pre><code>MassSpringDamper[sys]{m:0.1, k:10, d:0.3, x0:1, v0: 0};
PIDController[controller]{Kp:1, Ki:0.1, Kd:4);
ClosedLoopMSD{sys:sys, controller:controller};
F -&gt; ClosedLoopMSD:x -&gt; Scope;
</code></pre>
      <p>
       如果您设计好另一个控制器（比如滑模控制器）：
      </p>
      <pre><code>route SMC:CTRSignature(...; x; u)
    ...
end
</code></pre>
      <p>
       您可以很轻松地替换：
      </p>
      <pre><code>SMC[smc]{...};
ClosedLoopMSD{sys:sys, controller:smc};
</code></pre>
     </article>
    </div>
    <!-- Sidebar -->
    <aside class="col-sm-4">
     <div class="sidebar-box">
      <h4>
       目录
      </h4>
      <div class="list-group list-group-root">
       <a class="list-group-item" href="/ligral/quick-start.html">
        快速开始
       </a>
       <a class="list-group-item" href="/ligral/user-guide/index.html">
        用户文档
       </a>
       <div class="list-group">
        <a class="list-group-item" href="/ligral/user-guide/terms.html">
         术语定义
        </a>
        <a class="list-group-item" href="/ligral/user-guide/config.html">
         设置语句
        </a>
        <a class="list-group-item" href="/ligral/user-guide/const.html">
         声明常量
        </a>
        <a class="list-group-item" href="/ligral/user-guide/node.html">
         声明节点
        </a>
        <a class="list-group-item" href="/ligral/user-guide/link.html">
         节点连接
        </a>
        <a class="list-group-item" href="/ligral/user-guide/matrix.html">
         矩阵运算
        </a>
        <a class="list-group-item" href="/ligral/user-guide/route.html">
         路由类型
        </a>
        <a class="list-group-item active" href="/ligral/user-guide/signature.html">
         接口签名
        </a>
        <a class="list-group-item" href="/ligral/user-guide/import.html">
         引用依赖
        </a>
       </div>
       <a class="list-group-item" href="/ligral/dev-guide/index.html">
        开发文档
       </a>
       <div class="list-group">
        <a class="list-group-item" href="/ligral/dev-guide/syntax.html">
         语法设计
        </a>
        <a class="list-group-item" href="/ligral/dev-guide/interpreter.html">
         解释器
        </a>
        <a class="list-group-item" href="/ligral/dev-guide/component.html">
         模块组件
        </a>
        <a class="list-group-item" href="/ligral/dev-guide/simulation.html">
         问题抽象
        </a>
        <a class="list-group-item" href="/ligral/dev-guide/tools.html">
         工具箱
        </a>
       </div>
       <a class="list-group-item" href="/ligral/interface/index.html">
        接口定义
       </a>
       <div class="list-group">
        <a class="list-group-item" href="/ligral/interface/model.html">
         模块接口
        </a>
        <a class="list-group-item" href="/ligral/interface/protocol.html">
         数据接口
        </a>
       </div>
      </div>
     </div>
     <div class="sidebar-box sidebar-box-bg">
      <h4>
       关于我们
      </h4>
      <p>
       我们是一群有志于突破工业软件封锁、具有开源精神的开发者。本项目旨在替代 Simulink 进行仿真，通过与框图等效的文本语言描述仿真对象，并解释/编译而后求解。
       <a class="readmore" href="https://gitee.com/junruoyu-zheng/ligral/wikis" target="_blank">
        更多 »
       </a>
      </p>
     </div>
     <div class="sidebar-box">
      <h4>
       仓库链接
      </h4>
      <ul>
       <li>
        <a href="https://gitee.com/junruoyu-zheng/ligral" target="_blank" title="Gitee">
         Gitee 仓库
        </a>
       </li>
       <li>
        <a href="https://github.com/JRY-Zheng/ligral" target="_blank" title="GitHub">
         GitHub 仓库
        </a>
       </li>
      </ul>
     </div>
    </aside>
   </div>
  </main>
  <!-- Footer -->
  <footer class="footer">
   <div class="footer-lists">
    <div class="container">
     <div class="row">
      <div class="col-sm">
       <ul>
        <li>
         <h4>
          联系我们
         </h4>
        </li>
        <li>
         <a href="mailto:zhengjry@outlook.com">
          给我们发邮件
         </a>
        </li>
        <li>
         <a href="https://www.zhihu.com/people/LostFish" target="_blank">
          来知乎关注我
         </a>
        </li>
        <li>
         <a href="https://web.okjike.com/u/105ad022-f646-48c0-8236-6007ee5179c5" target="_blank">
          来即刻关注我
         </a>
        </li>
       </ul>
      </div>
      <div class="col-sm">
       <ul>
        <li>
         <h4>
          代码仓库
         </h4>
        </li>
        <li>
         <a href="https://gitee.com/junruoyu-zheng/ligral" target="_blank">
          Gitee 仓库
         </a>
        </li>
        <li>
         <a href="https://github.com/JRY-Zheng/ligral" target="_blank">
          GitHub 仓库
         </a>
        </li>
       </ul>
      </div>
      <div class="col-sm">
       <ul>
        <li>
         <h4>
          合作伙伴
         </h4>
        </li>
        <li>
         <a href="http://pyminer.com" target="_blank">
          PyMiner 官网
         </a>
        </li>
        <li>
         <a href="https://gitee.com/py2cn/pyminer" target="_blank">
          PyMiner 仓库地址
         </a>
        </li>
       </ul>
      </div>
      <div class="col-sm">
       <h4>
        致谢
       </h4>
       <p>
        Ligral 的开发得到了很多帮助，特在此致谢！感谢我的单位对创新的鼓励；感谢我的导师 James 对数值积分的指导；感谢 Gitee 对项目的支持，在刚开源不久就为我推荐；感谢 PyMiner 开发团队对我的鼓励和支持！
       </p>
       <p class="social-icons">
        <a href="https://gitee.com/junruoyu-zheng/ligral/stargazers" style="text-decoration: none;" target="_blank">
         <img alt="star" src="https://gitee.com/junruoyu-zheng/ligral/badge/star.svg?theme=dark"/>
        </a>
        <a href="https://www.zhihu.com/people/LostFish" target="_blank">
         <i class="fab fa-zhihu fa-2x zhihu-icon">
         </i>
        </a>
       </p>
      </div>
     </div>
    </div>
   </div>
   <div class="footer-bottom">
    <p class="text-center">
     Copyright © 2021. Ligral All rights reserved. 梨果科技版权所有 © 2021
    </p>
    <p class="text-center">
     <a href="#">
      <i class="fa fa-arrow-up">
      </i>
      回到顶部
     </a>
    </p>
   </div>
  </footer>
  <!-- Bootcamp JavaScript -->
  <!-- jQuery first, then Popper.js, then Bootstrap JS -->
  <script src="/ligral/js/jquery-3.2.1.slim.min.js">
  </script>
  <script src="/ligral/js/popper.min.js">
  </script>
  <script src="/ligral/js/bootstrap.min.js">
  </script>
  <script src="/ligral/js/TweenMax.min.js">
  </script>
  <script src="/ligral/js/rolling.js">
  </script>
 </body>
</html>